<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>DirDBM: Directory-based Storage</title>
  </head>

  <body>
<h1>DirDBM: Directory-based Storage</h1>

<h2>dirdbm.DirDBM</h2>

<p><code class="API">twisted.persisted.dirdbm.DirDBM</code> is a DBM-like storage system. 
That is, it stores mappings between keys
and values, like a Python dictionary, except that it stores the values in files
in a directory - each entry is a different file. The keys must always be strings,
as are the values. Other than that, <code class="API" base="twisted.persisted.dirdbm">DirDBM</code>
objects act just like Python dictionaries.</p>

<p><code class="API" base="twisted.persisted.dirdbm">DirDBM</code> is useful for cases
when you want to store small amounts of data in an organized fashion, without having
to deal with the complexity of a RDBMS or other sophisticated database. It is simple,
easy to use, cross-platform, and doesn't require any external C libraries, unlike
Python's built-in DBM modules.</p>

<pre class="python-interpreter">
&gt;&gt;&gt; from twisted.persisted import dirdbm
&gt;&gt;&gt; d = dirdbm.DirDBM("/tmp/dir")
&gt;&gt;&gt; d["librarian"] = "ook"
&gt;&gt;&gt; d["librarian"]        
'ook'
&gt;&gt;&gt; d.keys()
['librarian']
&gt;&gt;&gt; del d["librarian"]
&gt;&gt;&gt; d.items()
[]
</pre>

<h2>dirdbm.Shelf</h2>

<p>Sometimes it is neccessary to persist more complicated objects than strings.
With some care, <code base="twisted.persisted" class="API">dirdbm.Shelf</code>
can transparently persist
them. <code>Shelf</code> works exactly like <code>DirDBM</code>, except that
the values (but not the keys) can be arbitrary picklable objects. However,
notice that mutating an object after it has been stored in the
<code>Shelf</code> has no effect on the Shelf.
When mutating objects, it is neccessary to explictly store them back in the <code>Shelf</code>
afterwards:</p>

<pre class="python-interpreter">
&gt;&gt;&gt; from twisted.persisted import dirdbm
&gt;&gt;&gt; d = dirdbm.Shelf("/tmp/dir2")
&gt;&gt;&gt; d["key"] = [1, 2]
&gt;&gt;&gt; d["key"]
[1, 2]
&gt;&gt;&gt; l = d["key"]
&gt;&gt;&gt; l.append(3)
&gt;&gt;&gt; d["key"]
[1, 2]
&gt;&gt;&gt; d["key"] = l
&gt;&gt;&gt; d["key"]
[1, 2, 3]
</pre>





  </body>
</html>
